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This Technical Note discusses QuickDraw Auxiliary picture comments and how they can be 
used to help control the printing process. 



What's a Picture Comment? 

Picture comments are a way in which extra information beyond normal QuickDraw II calls can 
be embedded in a QuickDraw II picture. Comments can contain virtually anything; they consist 
of a length, a handle containing the comment and a "kind" that identifies the general type of 
information in the comment. Picture comment kinds less than or equal to 256 ($100) are 
reserved for Apple Computer, Inc. 

For comments to have any significance, there must be a way that a routine can take special action 
on them. One of the standard bottleneck procedures is called every time a picture comment is 
encountered, and it is passed the picture comment's kind, size, and handle on QuickDraw II's 
direct page. You can insert the address of a custom picture comment handler into the 
graf Procs field of a graf Port as described in Apple IlGS Technical Note #34, Low-Level 
QuickDraw II Routines. If no custom comment handler is present in the graf Port, the system 
calls its own StdComment routine, which ignores all comments. 

The current picture comment handling routine (either a custom one or the system's default one) 
is called whenever a picture comment is generated (with the QuickDraw Auxiliary call 
PicComment) or played back from a picture (from within DrawPicture). Since the picture 
comment handling procedure is called when the comment is created, a picture does not have to 
be open for this facility to work. 

Picture comments are ideal ways for applications to pass information to printer drivers as they 
are generated through toolbox calls and are easily accessible to any desktop program. If the 
printer driver is printing in immediate mode, it can intercept and act on the picture comment 
when it is generated. If the printer driver is printing in deferred mode and recording page images 
with QuickDraw II pictures, it can intercept and act on the picture comment when the picture is 
played back. 

Apple's Image Writer, Image Writer LQ and LaserWriter drivers (from System Software 5.0.3) all 
support various kinds of picture comments for controlling printed output. Applications are 
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encouraged to use these picture comments for finer control over printing. Authors of printer 
drivers are encouraged to act on these picture comments where appropriate, so applications 
which use them achieve similar results across printing platforms. 

The LaserWriter Driver's Picture Comments 

Version 2.2 and later of the LaserWriter driver support the following five PostScript® picture 
comments: 



Name 


Kind 


Size 


Handle 


PostScriptBegin 


190 





NIL 


PostScriptEnd 


191 





NIL 


PostScriptHandle 


192 




PostScript data 


PostScriptFile 


193 




PostScript path name 


Text I sPost Script 


194 





NIL 



Table 1— PostScript Picture Comments 



The print loop must be completed normally with or without any PostScript picture comments that 
are included. PostScript transmission must begin with the PostScriptBegin picture 
comment and end with the PostScriptEnd picture comment. Never nest 
PostScriptBegin and PostScriptEnd picture comments. 

The PostScriptHandle picture comment takes a handle containing PostScript commands 
(in the form of ASCII data) and sends it to the LaserWriter. The size field must contain the 
size of the handle. 

The PostScriptFile picture comment takes a handle containing the pathname of a disk file 
containing PostScript commands. The size field must contain the size of the pathname. 

The TextlsPostScript picture comment takes text drawn through the QuickDraw II 
StdText bottleneck and sends it to the LaserWriter as PostScript. This picture comment has 
the effect, from the application's point of view, of interpreting all strings passed to 
Drawstring and similar calls as PostScript. This picture comment is specific to LaserWriters 
(idev = $ 3). Other drivers do not implement this picture comment; therefore, text drawn 
through QuickDraw II is simply printed— it is neither interpreted as PostScript nor ignored. 

The driver does not check for PostScript errors, so the data sent to the LaserWriter must be 
correct. Always terminate PostScript text with a carriage return character. The transformation 
the driver uses flips text and prints it upside down on the page. Applications should set their 
own transformation matrices to serve their needs. Never use the LaserWriter's 
userdict— define a local dictionary for your application's use. Never use exit server, 
initgraphics, grestoreall, erasepage, or showpage PostScript commands, as 
these commands can alter the driver's environment. 
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See Chapter 3 of the LaserWriter Reference Manual for some examples of how to use picture 
comments. 
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The Image Writer Driver's Picture Comments 

Image Writer driver version 4.0 and later uses three picture comments to control alternate color 
selection: 

Name Kind Size Handle 

Reserved 250 - Reserved 

FillColorTable 251 42 See below 

ChangeSCBs 252 14 See below 



The structure passed in the handle to FillColorTable looks like the following: 



version 


word 


must be zero 


signature 


word 


must be $A55A 


tableno 


word 


the color table to be modified (0-15) 


table 


32 bytes 


The new color values for the color table 


reserved 


long 


must be zero 


ucture passed in the handle to ChangeSCBs looks like the following: 


version 


word 


must be zero 


signature 


word 


must be $A55A 


Yl 


word 


line number of first SCB to change (from zero to 






rPage.Y2) 


Y2 


word 


line number of last SCB to change (from zero to 






rPage.Y2) 


SCBvalue 


word 


the new scan line control byte 


reserved 


long 


must be zero 



PrOpenPage reinitializes the printing graf Port, so these picture comments should be used 
immediately after PrOpenPage to set custom colors. Having lines with both 320- and 640- 
mode is not recommended and will probably not be supported in the future. 

The ImageWriter driver uses picture comment 250 to internally mark the end of a page. 
Applications must not use this picture comment; use PrClosePage to end a page's definition. 



Further Reference 

• Apple IIgs Toolbox Reference, Volumes 1-3 

• Apple llGS Technical Note #34, Low-Level QuickDraw 11 Routines 

• Apple IlGS Technical Note #35, Printer Driver Specifications 

• Apple IlGS Technical Note #93, Compatible Printing 

• develop, October 1990, Issue 4, "Driving to Print" 

PostScript is a registered trademark of Adobe Systems, Incorporated. 
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